Replace Facade Proxy with handwritten proxy. by rhashimoto · Pull Request #285 · rhashimoto/wa-sqlite

rhashimoto · 2025-06-19T17:19:27Z

Using Proxy in the Facade implementation is convenient but has a performance cost. It is most noticeable with MemoryVFS and MemoryAsyncVFS; less so with VFS classes where persistent storage API calls (e.g. to OPFS and IndexedDB) become the bottleneck.

This PR replaces the use of Proxy in Facade with handwritten classes that have the same methods as Uint8Array and DataView for a small performance optimization.

gemini-code-assist

Summary of Changes

Hello @rhashimoto, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request focuses on a significant refactoring within the FacadeVFS to enhance performance. By replacing the existing JavaScript Proxy-based wrappers for WebAssembly memory access with custom-built proxy classes, I've aimed to reduce runtime overhead and provide more efficient handling of memory buffers, especially in scenarios where WebAssembly memory is frequently resized.

Highlights

Performance Optimization: I've replaced the use of built-in JavaScript Proxy objects within the FacadeVFS implementation with custom, handwritten classes (Uint8ArrayProxy and DataViewProxy). This change aims to reduce the performance overhead associated with Proxy objects, particularly noticeable in VFS implementations that primarily operate in memory, such as MemoryVFS and MemoryAsyncVFS.
Custom Buffer Handling for WebAssembly Memory: New Uint8ArrayProxy and DataViewProxy classes have been introduced. These classes mimic the behavior and methods of their native Uint8Array and DataView counterparts, respectively. Crucially, they include logic to automatically reacquire the underlying WebAssembly memory buffer when it is resized or detached, ensuring continued valid access to memory regions.
Refactored Memory Access Methods: The internal #makeTypedDataView and #makeDataArray methods in FacadeVFS have been updated. Instead of returning Proxy wrappers around native DataView or Uint8Array objects, they now instantiate and return instances of the newly created DataViewProxy and Uint8ArrayProxy classes.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces handwritten proxy classes (Uint8ArrayProxy and DataViewProxy) to replace the standard JavaScript Proxy mechanism for accessing WebAssembly memory in FacadeVFS.js to enhance performance. The new proxies correctly handle WebAssembly memory resizes. The review focuses on ensuring type clarity in JSDoc and addressing // @ts-ignore comments.

gemini-code-assist · 2025-06-19T17:21:10Z

src/examples/MemoryVFS.js


    // Copy data.
-    new Uint8Array(file.data, iOffset, pData.byteLength).set(pData);
+    new Uint8Array(file.data, iOffset, pData.byteLength).set(pData.subarray());


The change from pData to pData.subarray() is important and correct. It highlights that Uint8ArrayProxy is not a true Uint8Array.

gemini-code-assist · 2025-06-19T17:21:10Z

src/FacadeVFS.js

+    // @ts-ignore
+    return new DataViewProxy(this._module, byteOffset, type);


Consider changing the JSDoc return type to DataViewProxy for explicitness, or keep the JSDoc as DataView and add a brief comment explaining why ts-ignore is used (e.g., "DataViewProxy is a compatible subset of DataView"). This also applies to #makeDataArray.

gemini-code-assist · 2025-06-19T17:21:10Z

src/FacadeVFS.js

+   * is resized.
   * @param {number} byteOffset 
   * @param {number} byteLength 
+   * @returns {Uint8Array}


The JSDoc return type is Uint8Array, but the method returns Uint8ArrayProxy. It might be beneficial to briefly echo this in the JSDoc for #makeDataArray.

gemini-code-assist · 2025-06-19T17:21:10Z

src/FacadeVFS.js

+  }
+
+  /**
+   * @param {*} module


The JSDoc type for the module parameter is {*} which is very generic. To improve type safety and code clarity, consider specifying a more precise type based on its usage within the class.

Suggested change

* @param {*} module

* @param {{ HEAPU8: Uint8Array }} module

gemini-code-assist · 2025-06-19T17:21:10Z

src/FacadeVFS.js

+    return this.#array.subarray(begin, end);
+  }
+  toLocaleString(locales, options) {
+    // @ts-ignore


Could you confirm if this // @ts-ignore for toLocaleString is due to a TypeScript libdef limitation?

gemini-code-assist · 2025-06-19T17:21:10Z

src/FacadeVFS.js

+  }
+
+  /**
+   * @param {*} module


Similar to Uint8ArrayProxy, the JSDoc type for the module parameter is {*}. A more specific type would enhance clarity and type safety.

Suggested change

* @param {*} module

* @param {{ HEAPU8: { buffer: ArrayBuffer, byteOffset: number } }} module

* Replace Proxy with handwritten proxy for jRead/jWrite buffers. * Replace Proxy with handwritten proxy for VFS return data. --------- Co-authored-by: Roy Hashimoto <roy@shoestringresearch.com>

* Update issue templates * Replace Facade Proxy with handwritten proxy. (rhashimoto#285) * Replace Proxy with handwritten proxy for jRead/jWrite buffers. * Replace Proxy with handwritten proxy for VFS return data. --------- Co-authored-by: Roy Hashimoto <roy@shoestringresearch.com> * Use non-CAPTCHA SQLite download URL. (rhashimoto#289) * Use non-CAPTCHA SQLite download URL. * Use consistent Makefile variable bracing. --------- Co-authored-by: Roy Hashimoto <roy@shoestringresearch.com> * update build * added changeset --------- Co-authored-by: Roy Hashimoto <156154+rhashimoto@users.noreply.github.com> Co-authored-by: Roy Hashimoto <roy@shoestringresearch.com>

* Fix resetting isHandleRequested * Bump package version. * Fix hello demo import paths. * Permit JS booleans to be bound to queries, as integer 0/1 values (rhashimoto#272) * Permit boolean values to be bound to statements, as 0/1 * Add test for boolean binding * Using a single TextEncoder for all string conversions * Export HEAP* module members for recent EMSDK changes. * Bump tar-fs from 3.0.8 to 3.0.9 Bumps [tar-fs](https://github.com/mafintosh/tar-fs) from 3.0.8 to 3.0.9. - [Commits](mafintosh/tar-fs@v3.0.8...v3.0.9) --- updated-dependencies: - dependency-name: tar-fs dependency-version: 3.0.9 dependency-type: indirect ... Signed-off-by: dependabot[bot] <support@github.com> * Update SQLite to 3.50.1. * Bump package version. * Update issue templates * Replace Facade Proxy with handwritten proxy. (rhashimoto#285) * Replace Proxy with handwritten proxy for jRead/jWrite buffers. * Replace Proxy with handwritten proxy for VFS return data. --------- Co-authored-by: Roy Hashimoto <roy@shoestringresearch.com> * Use non-CAPTCHA SQLite download URL. (rhashimoto#289) * Use non-CAPTCHA SQLite download URL. * Use consistent Makefile variable bracing. --------- Co-authored-by: Roy Hashimoto <roy@shoestringresearch.com> * Fix WebLocksMixin state initialization. (rhashimoto#293) * Fix WebLocksMixin state initialization. * Don't fetch state in WebLocksMixin file control unnecessarily. * Minor fixes. --------- Co-authored-by: Roy Hashimoto <roy@shoestringresearch.com> * Bump package version. --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: Simon Binder <simon@journeyapps.com> Co-authored-by: Roy Hashimoto <roy@shoestringresearch.com> Co-authored-by: Grant Cox <grantc@ynab.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* Update issue templates * Replace Facade Proxy with handwritten proxy. (rhashimoto#285) * Replace Proxy with handwritten proxy for jRead/jWrite buffers. * Replace Proxy with handwritten proxy for VFS return data. --------- Co-authored-by: Roy Hashimoto <roy@shoestringresearch.com> * Use non-CAPTCHA SQLite download URL. (rhashimoto#289) * Use non-CAPTCHA SQLite download URL. * Use consistent Makefile variable bracing. --------- Co-authored-by: Roy Hashimoto <roy@shoestringresearch.com> * Fix WebLocksMixin state initialization. (rhashimoto#293) * Fix WebLocksMixin state initialization. * Don't fetch state in WebLocksMixin file control unnecessarily. * Minor fixes. --------- Co-authored-by: Roy Hashimoto <roy@shoestringresearch.com> * Bump package version. * Bump brace-expansion from 1.1.11 to 1.1.12 Bumps [brace-expansion](https://github.com/juliangruber/brace-expansion) from 1.1.11 to 1.1.12. - [Release notes](https://github.com/juliangruber/brace-expansion/releases) - [Commits](juliangruber/brace-expansion@1.1.11...v1.1.12) --- updated-dependencies: - dependency-name: brace-expansion dependency-version: 1.1.12 dependency-type: indirect ... Signed-off-by: dependabot[bot] <support@github.com> * Bump koa from 2.16.1 to 2.16.3 Bumps [koa](https://github.com/koajs/koa) from 2.16.1 to 2.16.3. - [Release notes](https://github.com/koajs/koa/releases) - [Changelog](https://github.com/koajs/koa/blob/master/History.md) - [Commits](koajs/koa@v2.16.1...v2.16.3) --- updated-dependencies: - dependency-name: koa dependency-version: 2.16.3 dependency-type: indirect ... Signed-off-by: dependabot[bot] <support@github.com> * Bump tar-fs from 3.0.9 to 3.1.1 Bumps [tar-fs](https://github.com/mafintosh/tar-fs) from 3.0.9 to 3.1.1. - [Commits](mafintosh/tar-fs@v3.0.9...v3.1.1) --- updated-dependencies: - dependency-name: tar-fs dependency-version: 3.1.1 dependency-type: indirect ... Signed-off-by: dependabot[bot] <support@github.com> * add changeset --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: Roy Hashimoto <156154+rhashimoto@users.noreply.github.com> Co-authored-by: Roy Hashimoto <roy@shoestringresearch.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

shoestringr added 2 commits June 19, 2025 09:59

Replace Proxy with handwritten proxy for jRead/jWrite buffers.

3a75d4c

Replace Proxy with handwritten proxy for VFS return data.

665aa0e

gemini-code-assist bot reviewed Jun 19, 2025

View reviewed changes

rhashimoto mentioned this pull request Jun 19, 2025

MemoryVFS should avoid creating Proxy objects in makeDataArray #273

Closed

2 tasks

gemini-code-assist bot reviewed Jun 19, 2025

View reviewed changes

rhashimoto merged commit 4f2b7e8 into master Jun 21, 2025
1 check passed

rhashimoto deleted the facade-proxy branch June 21, 2025 16:31

stevensJourney mentioned this pull request Aug 26, 2025

Update From Upstream powersync-ja/wa-sqlite#44

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Replace Facade Proxy with handwritten proxy.#285

Replace Facade Proxy with handwritten proxy.#285
rhashimoto merged 2 commits intomasterfrom
facade-proxy

rhashimoto commented Jun 19, 2025 •

edited

Loading

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

gemini-code-assist bot Jun 19, 2025

Uh oh!

gemini-code-assist bot Jun 19, 2025

Uh oh!

gemini-code-assist bot Jun 19, 2025

Uh oh!

gemini-code-assist bot Jun 19, 2025

Uh oh!

gemini-code-assist bot Jun 19, 2025

Uh oh!

gemini-code-assist bot Jun 19, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		// @ts-ignore
		return new DataViewProxy(this._module, byteOffset, type);

	* @param {*} module
	* @param {{ HEAPU8: { buffer: ArrayBuffer, byteOffset: number } }} module

Conversation

rhashimoto commented Jun 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Jun 19, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jun 19, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jun 19, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jun 19, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jun 19, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jun 19, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

rhashimoto commented Jun 19, 2025 •

edited

Loading